home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK1.toast / Development Kits (Disc 1) / Apple Guide / Engineering / APISample / APISampleMPW / Source / AppleGuide.h next >
Encoding:
C/C++ Source or Header  |  1994-07-07  |  7.2 KB  |  311 lines  |  [TEXT/MPS ]
  1. /***************************************************************************************
  2.  
  3.     File:        AppleGuide.h
  4.  
  5.     Contains:    Public interface to Apple Guide.
  6.  
  7.     Written by:    Dave Lyons and John R. Powers, III
  8.  
  9.     Copyright:    ©1994 by Apple Computer, Inc., all rights reserved.
  10.  
  11.     Change History (most recent first):
  12.     
  13.         <10> 07/06/94    PVC        Add gestaltAppleGuideIsDebug.
  14.         <9>     07/05/94    JRP        Change kAGFileMain to 'poco' (from 'help').
  15.         <8>  04/04/94    JRP        Beta seed
  16.  
  17. ***************************************************************************************/
  18.  
  19. #ifndef __APPLEGUIDE__
  20. #define __APPLEGUIDE__
  21.  
  22. #ifndef __APPLEEVENTS__
  23.     #include <AppleEvents.h>
  24. #endif
  25.             
  26. #ifndef __FILES__
  27.     #include <Files.h>
  28. #endif
  29.  
  30. #ifndef __TYPES__
  31.     #include <Types.h>
  32. #endif
  33.  
  34.  
  35. // Types
  36.  
  37. typedef unsigned long  UInt32;
  38. typedef unsigned short UInt16;
  39. typedef signed   short SInt16;
  40.  
  41. typedef UInt32 AGRefNum;
  42. typedef UInt32 AGCoachRefNum;
  43. typedef UInt32 AGContextRefNum;
  44.  
  45.  
  46. typedef struct AGAppInfo
  47. {
  48.     AEEventID    eventId;
  49.     long        refCon;
  50.     void*        contextObj;        // private system field
  51. }
  52.     AGAppInfo, *AGAppInfoPtr, **AGAppInfoHdl;
  53.  
  54. typedef pascal OSErr (*CoachReplyProcPtr)(Rect* pRect,
  55.                                             Ptr name,
  56.                                             long refCon);
  57.  
  58.  
  59. typedef pascal OSErr (*ContextReplyProcPtr)(Ptr pInputData,
  60.                                             Size inputDataSize,
  61.                                             Ptr *ppOutputData,
  62.                                             Size *pOutputDataSize,
  63.                                             AGAppInfoHdl hAppInfo);
  64.  
  65. // Constants
  66.  
  67. #define gestaltAppleGuidePresent    31
  68. #define gestaltAppleGuideIsDebug    30
  69. #define kAGDefault                    0
  70. #define kAGFrontDatabase            1
  71. #define    kAGNoMixin                    (-1)
  72.  
  73.  
  74. enum
  75. {
  76.     kAGViewFullHowdy =        1,        // Full-size Howdy
  77.     kAGViewTopicAreas =        2,        // Full-size Topic Areas
  78.     kAGViewIndex =            3,        // Full-size Index Terms
  79.     kAGViewLookFor =        4,        // Full-size Look-For (Search)
  80.     kAGViewSingleHowdy =    5,        // Single-list-size Howdy
  81.     kAGViewSingleTopics =    6        // Single-list-size Topics
  82. };
  83.  
  84.  
  85. enum
  86. {
  87.     kAGFileMain =    'poco',
  88.     kAGFileMixin =    'mixn'
  89. };
  90.  
  91.  
  92. enum AGDBTypeBit        // To test against AGGetAvailableDBTypes
  93. {
  94.     kAGDBTypeBitAny =        0x00000001,
  95.     kAGDBTypeBitHelp =        0x00000002,
  96.     kAGDBTypeBitTutorial =    0x00000004,
  97.     kAGDBTypeBitShortcuts =    0x00000008,
  98.     kAGDBTypeBitAbout =        0x00000010,
  99.     kAGDBTypeBitOther =        0x00000080
  100. };
  101.  
  102.  
  103. typedef UInt16 AGStatus;
  104. enum                    // Returned by AGGetStatus
  105. {
  106.     kAGIsNotRunning,
  107.     kAGIsSleeping,
  108.     kAGIsActive
  109. };
  110.  
  111.  
  112. typedef UInt16 AGWindowKind;
  113. enum                    // Returned by AGGetFrontWindowKind
  114. {
  115.     kAGNoWindow,
  116.     kAGAccessWindow,
  117.     kAGPresentationWindow
  118. };
  119.  
  120. // Error Codes
  121.  
  122. typedef SInt16 AGErr;    // Not an enum, because other OSErrs are valid.
  123. enum                    // Apple Guide error codes
  124. {
  125.     // -------------------- Apple event reply codes
  126.  
  127.     kAGErrUnknownEvent =        -2900,
  128.     kAGErrCantStartup =            -2901,
  129.     kAGErrNoAccWin =            -2902,
  130.     kAGErrNoPreWin =            -2903,
  131.     kAGErrNoSequence =            -2904,
  132.     kAGErrNotOopsSequence =        -2905,
  133.     kAGErrReserved06 =            -2906,
  134.     kAGErrNoPanel =                -2907,
  135.     kAGErrContentNotFound =        -2908,
  136.     kAGErrMissingString =        -2909,
  137.     kAGErrInfoNotAvail =        -2910,
  138.     kAGErrEventNotAvailable =    -2911,
  139.     kAGErrCannotMakeCoach =        -2912,
  140.     kAGErrSessionIDsNotMatch =    -2913,
  141.     kAGErrMissingDatabaseSpec =    -2914,
  142.  
  143.     // -------------------- Coach's Chalkboard reply codes
  144.  
  145.     kAGErrItemNotFound =            -2925,
  146.     kAGErrBalloonResourceNotFound =    -2926,
  147.     kAGErrChalkResourceNotFound =    -2927,
  148.     kAGErrChdvResourceNotFound =    -2928,
  149.     kAGErrAlreadyShowing =            -2929,
  150.     kAGErrBalloonResourceSkip =        -2930,
  151.     kAGErrItemNotVisible =            -2931,
  152.     kAGErrReserved32 =                -2932,
  153.     kAGErrNotFrontProcess =            -2933,
  154.     kAGErrMacroResourceNotFound =    -2934,
  155.  
  156.     // -------------------- API reply codes
  157.  
  158.     kAGErrAppleGuideNotAvailable =    -2951,
  159.     kAGErrCannotInitCoach =            -2952,
  160.     kAGErrCannotInitContext =        -2953,
  161.     kAGErrCannotOpenAliasFile =        -2954,
  162.     kAGErrNoAliasResource =            -2955,
  163.     kAGErrDatabaseNotAvailable =    -2956,
  164.     kAGErrDatabaseNotOpen =         -2957,
  165.     kAGErrMissingAppInfoHdl =        -2958,
  166.     kAGErrMissingContextObject =    -2959,
  167.     kAGErrInvalidRefNum =            -2960,
  168.     kAGErrDatabaseOpen =            -2961,
  169.     kAGErrInsufficientMemory =        -2962
  170.  
  171. };
  172.  
  173. // Events
  174.  
  175. typedef UInt32 AGEvent;    // Not an enum because we want to make assignments.
  176. enum                    // Handy events for AGGeneral.
  177. {
  178.         // Panel actions (Require a presentation window).
  179.     kAGEventDoCoach =            'doco',
  180.     kAGEventDoHuh =                'dhuh',
  181.     kAGEventGoNext =            'gonp',
  182.     kAGEventGoPrev =            'gopp',
  183.     kAGEventHidePanel =            'pahi',
  184.     kAGEventReturnBack =        'gobk',
  185.     kAGEventShowPanel =            'pash',
  186.     kAGEventTogglePanel =        'patg'
  187. };
  188.  
  189. // Functions
  190.  
  191. #ifdef __cplusplus
  192. extern "C" {
  193. #endif
  194.  
  195.     // AGClose
  196.     // Close the database associated with the AGRefNum.
  197.  
  198. pascal AGErr AGClose(AGRefNum *refNum)
  199.  = {0x7011,0xAA6E};
  200.  
  201.     // AGGeneral
  202.     // Cause various events to happen.
  203.  
  204. pascal AGErr AGGeneral(AGRefNum refNum, AGEvent theEvent)
  205.  = {0x700D,0xAA6E};
  206.  
  207.     // AGGetAvailableDBTypes
  208.     // Return the database types available for this application.
  209.  
  210. pascal UInt32 AGGetAvailableDBTypes(void)
  211.  = {0x7008,0xAA6E};
  212.  
  213.     // AGGetFrontWindowKind
  214.     // Return the kind of the front window.
  215.  
  216. pascal AGWindowKind AGGetFrontWindowKind(AGRefNum refNum)
  217.  = {0x700C,0xAA6E};
  218.  
  219.     // AGGetFSSpec
  220.     // Return the FSSpec for the AGRefNum.
  221.  
  222. pascal AGErr AGGetFSSpec(AGRefNum refNum, FSSpec* fileSpec)
  223.  = {0x700F,0xAA6E};
  224.  
  225.     // AGGetStatus
  226.     // Return the status of Apple Guide.
  227.  
  228. pascal AGStatus AGGetStatus(void)
  229.  = {0x7009,0xAA6E};
  230.  
  231.     // AGInstallCoachHandler
  232.     // Install a Coach object location query handler.
  233.  
  234. pascal AGErr AGInstallCoachHandler(CoachReplyProcPtr coachReplyProc, long refCon,
  235.         AGCoachRefNum *resultRefNum)
  236.  = {0x7012,0xAA6E};
  237.  
  238.     // AGInstallContextHandler
  239.     // Install a context check query handler.
  240.  
  241. pascal AGErr AGInstallContextHandler(ContextReplyProcPtr contextReplyProc,
  242.         AEEventID eventID, long refCon, AGContextRefNum *resultRefNum)
  243.  = {0x7013,0xAA6E};
  244.  
  245.     // AGIsDatabaseOpen
  246.     // Return true if the database associated with the AGRefNum is open.
  247.  
  248. pascal Boolean AGIsDatabaseOpen(AGRefNum refNum)
  249.  = {0x7006,0xAA6E};
  250.  
  251.     // AGOpen
  252.     // Open a guide database.
  253.  
  254. pascal AGErr AGOpen(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  255.                         AGRefNum *resultRefNum)
  256.  = {0x7001,0xAA6E};
  257.  
  258.     // AGOpenWithSearch
  259.     // Open a guide database and preset a search string.
  260.  
  261. pascal AGErr AGOpenWithSearch(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  262.                                 ConstStr255Param searchString,
  263.                                 AGRefNum *resultRefNum)
  264.  = {0x7002,0xAA6E};
  265.  
  266.     // AGOpenWithSequence
  267.     // Open a guide database and display a presentation window sequence.
  268.  
  269. pascal AGErr AGOpenWithSequence(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  270.                                 short sequenceID,
  271.                                 AGRefNum *resultRefNum)
  272.  = {0x7004,0xAA6E};
  273.  
  274.     // AGOpenWithView
  275.     // Open a guide database and override the default view.
  276.  
  277. pascal AGErr AGOpenWithView(FSSpec *fileSpec, UInt32 flags, Handle mixinControl,
  278.                                 short viewNum,
  279.                                 AGRefNum *resultRefNum)
  280.  = {0x7005,0xAA6E};
  281.  
  282.     // AGQuit
  283.     // Make Apple Guide quit.
  284.  
  285. pascal AGErr AGQuit(void)
  286.  = {0x7010,0xAA6E};
  287.  
  288.     // AGRemoveCoachHandler
  289.     // Remove the Coach object location query handler.
  290.  
  291. pascal AGErr AGRemoveCoachHandler(AGCoachRefNum *resultRefNum)
  292.  = {0x7014,0xAA6E};
  293.  
  294.     // AGRemoveContextHandler
  295.     // Remove the context check query handler.
  296.  
  297. pascal AGErr AGRemoveContextHandler(AGContextRefNum *resultRefNum)
  298.  = {0x7015,0xAA6E};
  299.  
  300.     // AGStart
  301.     // Start up Apple Guide in the background.
  302.  
  303. pascal AGErr AGStart(void)
  304.  = {0x700A,0xAA6E};
  305.  
  306. #ifdef __cplusplus
  307. }
  308. #endif
  309.  
  310. #endif // __APPLEGUIDE__
  311.